# 架构设计

模块由两大并列子目录构成：docs/ 与 firmware/。
- docs/ 采用 Sphinx RST 文档体系，顶层 index.rst 通过 toctree 组织 1_hardware（硬件规格）、2_software（环境搭建）、3_examples（按 basics/advance/classic/Agent/AudioAI 分类的示例）、4_xiaozhi（小智语音助手专题）、5_api（library/mPython/micropython/pythonStd/mpy_ref 四级 API 参考）、6_C_program（Arduino/PlatformIO/ESP-IDF 开发指南）、7_faq；boards/ledong_v2/ 下为独立板型的镜像文档树，各自带 conf.py/Makefile 可单独构建。
- firmware/ 是 ESP-IDF v5.x + CMake 工程，顶层 CMakeLists.txt 通过 MICROPY_BOARD 变量选择 boards/<board>/mpconfigboard.cmake 并合并多个 sdkconfig.* 生成最终配置；默认 board 为 mpython_v3，另支持 labplus_Ledong_v2、labplus_for_xuejing、labplus_xunfei_js_middle、labplus_xunfei_js_primary 五类板型，每块板提供 board.json、manifest.py、mpconfigboard.h/.cmake、partitions-*.csv、sdkconfig.* 等板级描述文件。
- 固件分层清晰：builtins/ 存放编译进固件的 C 扩展（machine_i2c、machine_pin、modmusic、modmotion、modframebuf、network_wlan、esp32_nvs、icon 等），modules/ 存放运行时加载的 Python 模块（传感器驱动如 apds9960/max30102/hcsr04、网络 siot/xunfei/ai_cloud、BLE mpython_ble、GUI gui.py/lv_utils、字体 font/ 等），components/ 包含 IDF 组件 esp_lcd_jd9853（JD9853 屏幕驱动）与 gen_bmgr_codes（板管理器代码生成），drivers/mpu6050/ 集成 eMPL/Motion Processing Library 实现 IMU 融合算法，file_system/ 按板型组织 LVGL UI 与业务脚本（main.py/lv_gui.py/lv_oled.py），examples/ 提供 GUI/audio/tft_display/xuejing_hw_test 等演示程序。
- 构建产物通过 makeimg.py 在 merge_bin 目标中打包，qstrdefsport.h 管理字符串表，usercmodule/（被注释启用）用于第三方 C 模块集成。